<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">

<head>
	<meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
	<title>LOOP: Event Timer</title>
	<style type="text/css" media="all"><!--
		@import "../../loop.css";
		@import "../../layout1.css";
	--></style>
</head>

<body>

<div id="Header">Class Models for Lua</div>
<div id="Logo"><img alt="small (1K)" src="../../small.gif" height="70"></div>

<div id="Menu">
<div class="outside"><div class="inside"><ul>
																																																																																																																																																													<li><a href="../../index.html", title="">Home</a></li>
																																																																																																																																																													<li><a href="../../release/index.html", title="Installation">Install</a></li>
																																																																																																																																																													<li><a href="../../manual/index.html", title="User Manual">Manual</a></li>
																																																																																																																																																													<li><a href="../index.html", title="Class Library">Library</a>
																																																																																																																																																														<div class="outside"><div class="inside"><ul>
																																																																																																																																																															<li><a href="../overview.html#collection", title="Collections">collection</a>
																																																																																																																																																																</li>
																																																																																																																																																																<li><a href="../overview.html#compiler", title="Compiling">compiler</a>
																																																																																																																																																																	</li>
																																																																																																																																																																	<li><a href="../overview.html#debug", title="Debugging">debug</a>
																																																																																																																																																																		</li>
																																																																																																																																																																		<li><a href="../overview.html#object", title="Objects">object</a>
																																																																																																																																																																			</li>
																																																																																																																																																																			<li><a href="../overview.html#serial", title="Serialization">serial</a>
																																																																																																																																																																				</li>
																																																																																																																																																																				<li><a href="../overview.html#thread", title="Threading">thread</a>
																																																																																																																																																																					</li>
																																																																																																																																																																				</ul></div></div>
																																																																																																																																																																			</li>
																																																																																																																																																																			<li><a href="../../contact.html", title="Contact People">Contact</a></li>
																																																																																																																																																																			<li><a href="http://luaforge.net/projects/oil/", title="Project at LuaForge">LuaForge</a></li>
																																																																																																																																																																		</ul></div></div>
																																																																																																																																																																	
</div>

<div class="content">
<h1>Event Timer</h1>
<h2><code>loop.thread.Timer</code></h2><br>
<p>Class of objects that triggers a function continuously in a regular rate.
It also avoids accumulation of triggering events if the function execution overlaps the time of the next event.
In such case, the overlapped event is canceled.
This class is useful to implement monitors that are executed from time to time in a cooperative multi-threaded application.</p>

<p>Each instance is bounded to an instance of <code><a href="Scheduler.html">Scheduler</a></code> which is used to register a thread that executes continuously the triggered function and sleeps until the time for the next execution.
It also measures the time the function execution lasted in order to avoid accumulation of delayed execution.</p>

<h2>Behavior</h2>

<h3>Initialization</h3>

<dl>
	
	<dt><code><b>Timer</b>([object])</code></dt>
	<dd>
		Makes <code>object</code> an instance of <code>Timer</code>.
		It also creates the thread that continously executes the defined action.
		If no <code>object</code> is provided, a new table is created to represent the new instance.
	</dd>
	
</dl>

<h3>Fields</h3>

<dl>
	
	<dt><code><b>action</b></code></dt>
	<dd>
		Function called at each triggering event.
	</dd>
	
	<dt><code><b>enabled</b></code></dt>
	<dd>
		Boolean value that indicates if the timer is enabled or not.
		This field should not be changed by the application.
		To do so, use the methods <code>enable</code> and <code>disable</code>.
	</dd>
	
	<dt><code><b>rate</b></code></dt>
	<dd>
		Time rate, in seconds, that the function <code>action</code> should be executed.
	</dd>
	
	<dt><code><b>scheduler</b></code></dt>
	<dd>
		Object that implements the API of <code><a href="Scheduler.html">Scheduler</a></code> and is used to register the thread that executes the timer.
	</dd>
	
	<dt><code><b>thread</b></code></dt>
	<dd>
		Co-routine that implements the thread that executes the timer.
		This thread is registered in the object of field <code>scheduler</code> when the timer is enabled.
	</dd>
	
</dl>

<h3>Methods</h3>

<dl>
	
	<dt><code><b>timer</b>()</code></dt>
	<dd>
		Method that implements the timer behavior.
		This is the function executed by the timer thread.
	</dd>
	
	<dt><code><b>enable</b>()</code></dt>
	<dd>
		Method that enables the execution of the timer to start triggering the defined action.
	</dd>
	
	<dt><code><b>disable</b>()</code></dt>
	<dd>
		Method that disables the execution of the timer preventing that the action be executed again.
	</dd>
	
</dl>

<h2>Remarks</h2>

<ul>
	<li>
		The time precision of the timer depends on the precision provided by object of field <code>scheduler</code>.
	</li>
</ul>

<h2>Examples</h2>

<h3><a name="$ExampleName">$ExampleDescription</a></h3>

<pre>
-- example missing
</pre>

</div>

<div class="content">
<p><small><strong>Copyright (C) 2004-2008 Tecgraf, PUC-Rio</strong></small></p>
<small>This project is currently being maintained by <a href="http://www.tecgraf.puc-rio.br">Tecgraf</a> at <a href="http://www.puc-rio.br">PUC-Rio</a>.</small>
</div>



</body>

</html>
